sdk/samples/all in on code/Visual Studio 2008/CSVSPackageToolbars/ReadMe.txt

   1 =============================================================================
   2             CSVSToolBars Module: CSVSToolBars Project Overview
   3 =============================================================================
   4
   5 /////////////////////////////////////////////////////////////////////////////
   6 Use:
   7
   8 VSPackages are software modules that make up and extend the Visual Studio
   9 integrated development environment (IDE) by providing UI elements, services,
  10 projects, editors, and designers. VSPackages are the principal architectural
  11 unit of Visual Studio, and are the unit of deployment, licensing, and security
  12 also. Visual Studio itself is written mostly as a collection of VSPackages.
  13 This sample demonstrate how to use the the Visual Studio Integration Package
  14 Wizard to create a simple VSPackage with a toolbar.
  15
  16
  17 //////////////////////////////////////////////////////////////////////////////
  18 Prerequisites:
  19
  20 VS 2008 SDK must be installed on the machine. You can download it from:
  21 http://www.microsoft.com/downloads/details.aspx?FamilyID=30402623-93ca-479a-867c-04dc45164f5b&displaylang=en
  22
  23 Otherwise the project may not be opened by Visual Studio.
  24
  25 If you run this project on a x64 OS, please also config the Debug tab of the project
  26 Setting. Set the "Start external program" to
  27 C:\Program Files(x86)\Microsoft Visual Studio 9.0\Common7\IDE\devenv.exe
  28
  29 NOTE: The Package Load Failure Dialog occurs because there is no PLK(Package Load Key)
  30       Specified in this package. To obtain a PLK, please to go to WebSite:
  31       http://msdn.microsoft.com/en-us/vsx/cc655795.aspx
  32       More info
  33       http://msdn.microsoft.com/en-us/library/bb165395.aspx
  34
  35 /////////////////////////////////////////////////////////////////////////////
  36 Creation:
  37
  38 A: How to Create a VSPackage
  39
  40         1. Create a new project using Visual Studio Integration Package as template
  41            (New Project dialog box -> Other Project Types -> Extensibility).
  42
  43         2. In the Location box, type the file path for your VSPackage.
  44
  45         3. In the Name box, type the name for the solution and then click OK to start
  46            the wizard.
  47
  48         3. On the Select a Programming Language page, select Visual C# and have the
  49            wizard generate a key.snk file to sign the assembly, then click Next.
  50
  51         4. In the Basic VSPackage Information page, specify details about your
  52            VSPackage(Brand the VSPackage) and click Next.
  53
  54         5. Select the Menu Command option to create a new command for the VSPackage. Then
  55            click Next.
  56
  57         6. Type the name(All-In-One) and ID(cmdidMyCommand) for the new
  58            menu command in the text boxes, then click Next. The command ID is the name
  59            of a constant that represents this menu command in the generated code.
  60
  61         7. Uncheck the Intergration Test Project and Unit Test Project, then click
  62            Finish.
  63
  64 B: Add a Toolbar to VS IDE
  65
  66         1. In Solution Explorer, open CSVSToolbars.vsct.
  67            VSCT file stands for Visual Studio Command Table. This is an XML based file that
  68            describes the layout and appearance of command items for a VSPackage. Command
  69            items include buttons, combo boxes, menus, toolbars, and groups of command items.
  70
  71         2. In the <Symbols> section, find the <GuidSymbol> node whose name attribute is
  72            guidCSVSToolbarsCmdSet. Add the following two <IDSymbol> elements to the list of
  73            <IDSymbol> elements in this node to define a toolbar and a toolbar group.
  74
  75            <IDSymbol name="ToolbarID" value="0x1000" />
  76        <IDSymbol name="ToolbarGroupID" value="0x1001" />
  77
  78         3. Just above the <Groups> section, create an empty <Menus> section, and create the
  79            following <Menu> element to define the toolbar that you declared in step 2.
  80
  81            <Menus>
  82         <Menu guid="guidCSVSToolbarsCmdSet" id="ToolbarID"
  83               priority="0x0000" type="Toolbar">
  84           <Parent guid="guidCSVSToolbarsCmdSet" id="ToolbarID" />
  85           <Strings>
  86             <ButtonText>My Toolbar</ButtonText>
  87             <CommandName>My Toolbar</CommandName>
  88           </Strings>
  89         </Menu>
  90        </Menus>
  91
  92     4. Add a new <Group> element to the <Groups> section to define the group that you
  93        declared in the <Symbols> section.
  94
  95        <Group guid="guidCSVSToolbarsCmdSet" id="ToolbarGroupID"
  96               priority="0x0000">
  97          <Parent guid="guidCSVSToolbarsCmdSet" id="ToolbarID"/>
  98        </Group>
  99
 100     5. In the Buttons Element, change the parent of the existing Button Elementto the
 101        toolbar group so that the toolbar will be displayed.
 102
 103        <Parent guid="guidCSVSToolbarsCmdSet" id="ToolbarGroupID" />
 104
 105     6. Save CSVSToolbars.vsct.
 106
 107
 108 C: Add a icon to the command:
 109
 110     1. Create a bitmap with a color depth of 32-bits. An icon is always 16 x 16 so this
 111        bitmap must be 16 pixels high and a multiple of 16 pixels wide.In this sample, it
 112        is camera.png, which is a 32bits png image.
 113
 114     2. Add the bitmap to the resource of this project
 115
 116     3. Open the .vsct file in the editor.
 117
 118     4. In the Symbols Element, find the GuidSymbol Element that contains your existing
 119        bitmap entries. By default, it is named guidImages. And add new Symbols Element next
 120        to the existing one.
 121
 122                         <GuidSymbol name="guidMyImages" value="{4056cc26-4a2f-432c-a816-e6694e673abb}">
 123                           <IDSymbol name="bmpMyPic" value="1" />
 124                         </GuidSymbol>
 125
 126     5. Add an IDSymbol Element for each icon in your bitmap. The name attribute is the
 127        icon's ID, and the value indicates its position on the strip.
 128
 129                   <IDSymbol name="bmpMyPic" value="1" />
 130
 131     6. Create a Bitmap Element in the <Bitmaps> section of the .vsct file to represent the
 132        bitmap containing the icons.
 133
 134             <Bitmap guid="guidMyImages" href="Resources\camera.png"/>
 135
 136     7.Change the Toolbar button to use the new icon
 137
 138             <Icon guid="guidMyImages" id="bmpMyPic" />
 139
 140     8. Save all the files.
 141
 142
 143  D: Add a menu controller
 144
 145     1. Open the .vsct file in the editor.
 146
 147     2. In the Symbols Element, in the GuidSymbol Element named "guidCSVSToolbarsCmdSet",
 148        declare your menu controller, menu controller group, and three menu items
 149
 150           <IDSymbol name="TestMenuController" value="0x1300"/>
 151                   <IDSymbol name="TestMenuControllerGroup" value="0x1060"/>
 152                   <IDSymbol name="cmdidMCItem1" value="0x0130"/>
 153                   <IDSymbol name="cmdidMCItem2" value="0x0131"/>
 154                   <IDSymbol name="cmdidMCItem3" value="0x0132"/>
 155
 156         3.In Menus Element,after the last menu entry, define the menu controller as a menu.
 157
 158                   <Menu guid="guidCSVSToolbarsCmdSet" id="TestMenuController"
 159                           priority="0x0100" type="MenuController">
 160                         <Parent guid="guidCSVSToolbarsCmdSet" id="ToolbarGroupID"/>
 161                         <CommandFlag>IconAndText</CommandFlag>
 162                         <CommandFlag>TextChanges</CommandFlag>
 163                         <CommandFlag>TextIsAnchorCommand</CommandFlag>
 164                         <Strings>
 165                           <ButtonText>Test Menu Controller</ButtonText>
 166                           <CommandName>Test Menu Controller</CommandName>
 167                         </Strings>
 168                   </Menu>
 169
 170         4. In the Groups Element, after the last group entry, add the menu controller group
 171
 172                   <Group guid="guidCSVSToolbarsCmdSet" id="TestMenuControllerGroup"
 173                    priority="0x000">
 174                         <Parent guid="guidCSVSToolbarsCmdSet" id="TestMenuController"/>
 175                   </Group>
 176
 177         5. In the Buttons Element, after the last button entry, add a Button Element for each of
 178            your menu items.
 179
 180                   <Button guid="guidCSVSToolbarsCmdSet" id="cmdidMCItem1"
 181                   priority="0x0000" type="Button">
 182                         <Parent guid="guidCSVSToolbarsCmdSet" id="TestMenuControllerGroup"/>
 183                         <Icon guid="guidImages" id="bmpPic1"/>
 184                         <CommandFlag>IconAndText</CommandFlag>
 185                         <Strings>
 186                           <ButtonText>MC Item 1</ButtonText>
 187                           <CommandName>MC Item 1</CommandName>
 188                         </Strings>
 189                   </Button>
 190                   <Button guid="guidCSVSToolbarsCmdSet" id="cmdidMCItem2"
 191                                 priority="0x0100" type="Button">
 192                         <Parent guid="guidCSVSToolbarsCmdSet" id="TestMenuControllerGroup"/>
 193                         <Icon guid="guidImages" id="bmpPic2"/>
 194                         <CommandFlag>IconAndText</CommandFlag>
 195                         <Strings>
 196                           <ButtonText>MC Item 2</ButtonText>
 197                           <CommandName>MC Item 2</CommandName>
 198                         </Strings>
 199                   </Button>
 200                   <Button guid="guidCSVSToolbarsCmdSet" id="cmdidMCItem3"
 201                                 priority="0x0200" type="Button">
 202                         <Parent guid="guidCSVSToolbarsCmdSet" id="TestMenuControllerGroup"/>
 203                         <Icon guid="guidImages" id="bmpPicSearch"/>
 204                         <CommandFlag>IconAndText</CommandFlag>
 205                         <Strings>
 206                           <ButtonText>MC Item 3</ButtonText>
 207                           <CommandName>MC Item 3</CommandName>
 208                         </Strings>
 209                   </Button>
 210
 211         6. Save the .vsct file.
 212
 213  E: Implement the menu controller
 214
 215     1. Open PkgCmdID.cs and add the following lines
 216
 217         public const int cmdidMCItem1 = 0x130;
 218         public const int cmdidMCItem2 = 0x131;
 219         public const int cmdidMCItem3 = 0x132;
 220
 221     2. At the top of the CSVSToolbarsPackage class, add the following:
 222
 223         private int currentMCCommand; // The currently selected menu controller command
 224
 225         3. In the Initialize method, immediately after the last call to the AddCommand method,
 226            add code to route the events for each command through the same handlers.
 227
 228                 for (int i = PkgCmdIDList.cmdidMCItem1; i <=
 229                    PkgCmdIDList.cmdidMCItem3; i++)
 230                 {
 231                     CommandID cmdID = new
 232                     CommandID(GuidList.guidCSVSToolbarsCmdSet, i);
 233                     OleMenuCommand mc = new OleMenuCommand(new
 234                       EventHandler(OnMCItemClicked), cmdID);
 235                     mc.BeforeQueryStatus += new EventHandler(OnMCItemQueryStatus);
 236                     mcs.AddCommand(mc);
 237                     // The first item is, by default, checked.
 238                     if (PkgCmdIDList.cmdidMCItem1 == i)
 239                     {
 240                         mc.Checked = true;
 241                         this.currentMCCommand = i;
 242                     }
 243                 }
 244
 245         4. Add the following two event handler defined above
 246
 247             private void OnMCItemClicked(object sender, EventArgs e)
 248         {
 249             OleMenuCommand mc = sender as OleMenuCommand;
 250             if (null != mc)
 251             {
 252                 string selection;
 253                 switch (mc.CommandID.ID)
 254                 {
 255                     case PkgCmdIDList.cmdidMCItem1:
 256                         selection = "Menu controller Item 1";
 257                         break;
 258
 259                     case PkgCmdIDList.cmdidMCItem2:
 260                         selection = "Menu controller Item 2";
 261                         break;
 262
 263                     case PkgCmdIDList.cmdidMCItem3:
 264                         selection = "Menu controller Item 3";
 265                         break;
 266
 267                     default:
 268                         selection = "Unknown command";
 269                         break;
 270                 }
 271                 this.currentMCCommand = mc.CommandID.ID;
 272
 273                 IVsUIShell uiShell =
 274                   (IVsUIShell)GetService(typeof(SVsUIShell));
 275                 Guid clsid = Guid.Empty;
 276                 int result;
 277                 uiShell.ShowMessageBox(
 278                            0,
 279                            ref clsid,
 280                            "Test Tool Window Toolbar Package",
 281                            string.Format(CultureInfo.CurrentCulture,
 282                                          "You selected {0}", selection),
 283                            string.Empty,
 284                            0,
 285                            OLEMSGBUTTON.OLEMSGBUTTON_OK,
 286                            OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST,
 287                            OLEMSGICON.OLEMSGICON_INFO,
 288                            0,
 289                            out result);
 290             }
 291         }
 292
 293         5. Save the all files.
 294
 295  E: Testing the Tool Window
 296
 297     1. Press F5 to open a new instance of the Visual Studio experimental build.
 298
 299     2. On the View menu, point to Toolbars and then click My Toolbar.
 300
 301     3. Click the Load File button on the Tool Window and Select a media file.
 302
 303
 304 /////////////////////////////////////////////////////////////////////////////
 305 References:
 306
 307 How to: Create VSPackages (C# and Visual Basic)
 308 http://msdn.microsoft.com/en-us/library/bb164725.aspx
 309
 310 How to: Register a VSPackage (C#)
 311 http://msdn.microsoft.com/en-us/library/bb166544.aspx
 312
 313 VSPackage Tutorial 1: How to Create a VSPackage
 314 http://msdn.microsoft.com/en-us/library/cc138589.aspx
 315
 316 Designing XML Command Table (.Vsct) Files
 317 http://msdn.microsoft.com/en-us/library/bb166366.aspx
 318
 319 Commands Element
 320 http://msdn.microsoft.com/en-us/library/bb165399.aspx
 321
 322 KeyBindings Element
 323 http://msdn.microsoft.com/en-us/library/bb165085.aspx
 324
 325 Walkthrough: Adding a Toolbar to the IDE
 326 http://msdn.microsoft.com/en-us/library/bb164715.aspx
 327
 328 How to: Add Icons to Commands on Toolbars
 329 http://msdn.microsoft.com/en-us/library/bb165158.aspx
 330
 331 How to: Add Menu Controllers to Toolbars
 332 http://msdn.microsoft.com/en-us/library/bb166443.aspx
 333
 334 Walkthrough: Adding a Menu Controller to a Toolbar
 335 http://msdn.microsoft.com/en-us/library/bb165748.aspx
 336
 337 Creating a package with a simple command
 338 http://dotneteers.net/blogs/divedeeper/archive/2008/01/06/LearnVSXNowPart3.aspx
 339
 340 Menus and comands in VS IDE
 341 http://dotneteers.net/blogs/divedeeper/archive/2008/02/22/LearnVSXNowPart13.aspx
 342
 343
 344 /////////////////////////////////////////////////////////////////////////////
 345
 346
 347